--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
docs/meshchatx_on_raspberry_pi.md legacy/win7 (159b2358) Text, 6.61 KB
MeshChatX on Raspberry Pi
This guide shows a simple headless setup for running MeshChatX on a Raspberry Pi 4
with a web UI you can access from another device on your network.
This install path uses a release wheel, which already includes frontend assets.
Automated Setup Scripts
T282828
curl -fsSL Ta5d6ff'https://raw.githubusercontent.com/Quad4-Software/MeshChatX/refs/heads/master/scripts/rpi/install_meshchatx.sh' Tb4b4b4| bash
If you have the repo cloned locally already:
T282828
bash scripts/rpi/install_meshchatx.sh
The installer guides you through:
• Optional T383838espeak-ng install (tries apt/dnf/pacman)
• Install method (T383838pipx or T383838venv + pip)
• Wheel choice (latest stable, latest pre-release, or a custom URL)
• Optional cosign attestation: if a T383838*.whl.cosign.bundle is published
next to the wheel, you can verify it. The script uses T383838cosign on T383838PATH if
present, or downloads a checksum-verified official Linux binary to T383838/tmp
(the Sigstore bundle format is not reimplemented in shell; you still use the
real T383838cosign to verify, without installing a distro package)
• Storage and Reticulum directories
• Bind host and port (with availability check)
• HTTPS on/off (default on)
• Service mode (T383838system, T383838user, or T383838none)
• Service startup validation via the HTTP status endpoint
If startup validation fails, it prints recent logs and stops the service to avoid
restart loops.
1) Install Base Dependencies
T282828
sudo apt update
sudo apt upgrade -y
sudo apt install -y python3 python3-pip pipx
2) Enable pipx Path
T282828
pipx ensurepath
Tffa657source ~/.profile
If T383838pipx is not available in your distro package repo, install it with:
T282828
python3 -m pip install --user pipx
python3 -m pipx ensurepath
Tffa657source ~/.profile
3) Install MeshChatX with pipx (recommended)
Preferred option (recommended): install from a release wheel (4.7.0 or newer),
because the wheel bundles frontend assets.
T282828
pipx install /path/to/reticulum_meshchatx-<version>-py3-none-any.whl
Direct example (v4.7.0):
T282828
pipx install Ta5d6ff"https://github.com/Quad4-Software/MeshChatX/releases/download/v4.7.0/reticulum_meshchatx-4.7.0-py3-none-any.whl"
T383838py3-none-any wheels are architecture-independent, so the same wheel artifact
works on Raspberry Pi ARM and x86_64 Linux systems.
Upgrade example:
T282828
pipx upgrade meshchatx
4) Install MeshChatX without pipx (venv + pip)
If you prefer not to use pipx:
T282828
mkdir -p ~/meshchatx
Tffa657cd ~/meshchatx
python3 -m venv .venv
Tffa657source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install Ta5d6ff"https://github.com/Quad4-Software/MeshChatX/releases/download/v4.7.0/reticulum_meshchatx-4.7.0-py3-none-any.whl"
Run command in venv mode:
T282828
~/meshchatx/.venv/bin/meshchatx --headless --host T79c0ff0.0.0.0 --port T79c0ff8000
5) Run MeshChatX (Headless)
T282828
meshchatx --headless --host T79c0ff0.0.0.0 --port T79c0ff8000
Then open:
T282828
http://<pi-ip>:8000
6) Configure a systemd Service
T383838systemd keeps MeshChatX running in the background and starts it automatically
on boot.
You have two service styles:
• System service (T383838/etc/systemd/system/...) for always-on host services.
• User service (T383838~/.config/systemd/user/...) for per-user sessions.
Option A: System service (recommended for Pi node/server use)
Create T383838/etc/systemd/system/meshchatx.service:
T282828
Tff7b72[Unit]
Te6edf3DescriptionTff7b72=Ta5d6ffMeshChatX Headless (system service)
Te6edf3AfterTff7b72=Ta5d6ffnetwork-online.target
Te6edf3WantsTff7b72=Ta5d6ffnetwork-online.target
Tff7b72[Service]
Te6edf3TypeTff7b72=Ta5d6ffsimple
Te6edf3UserTff7b72=Ta5d6ffpi
Te6edf3GroupTff7b72=Ta5d6ffpi
Te6edf3WorkingDirectoryTff7b72=Ta5d6ff/home/pi/meshchatx
Te6edf3EnvironmentTff7b72=Ta5d6ff"Ta5d6ffPATH=/home/pi/.local/bin:/usr/bin:/binTa5d6ff"
Te6edf3ExecStartTff7b72=Ta5d6ff/home/pi/.local/bin/meshchatx --headless --host 0.0.0.0 --port 8000 --storage-dir /home/pi/meshchatx/storage --reticulum-config-dir /home/pi/.reticulum
Te6edf3RestartTff7b72=Ta5d6ffalways
Te6edf3RestartSecTff7b72=Ta5d6ff3
Tff7b72[Install]
Te6edf3WantedByTff7b72=Ta5d6ffmulti-user.target
The above service file is for pipx installs. For venv installs, use:
T282828
Tff7b72[Service]
Te6edf3TypeTff7b72=Ta5d6ffsimple
Te6edf3UserTff7b72=Ta5d6ffpi
Te6edf3GroupTff7b72=Ta5d6ffpi
Te6edf3WorkingDirectoryTff7b72=Ta5d6ff/home/pi/meshchatx
Te6edf3EnvironmentTff7b72=Ta5d6ff"Ta5d6ffPATH=/home/pi/meshchatx/.venv/bin:/usr/bin:/binTa5d6ff"
Te6edf3ExecStartTff7b72=Ta5d6ff/home/pi/meshchatx/.venv/bin/meshchatx --headless --host 0.0.0.0 --port 8000 --storage-dir /home/pi/meshchatx/storage --reticulum-config-dir /home/pi/.reticulum
Te6edf3RestartTff7b72=Ta5d6ffalways
Te6edf3RestartSecTff7b72=Ta5d6ff3
Update T383838User, T383838Group, and paths if your install location is different.
Enable and start:
T282828
mkdir -p /home/pi/meshchatx/storage /home/pi/.reticulum
sudo chown -R pi:pi /home/pi/meshchatx
sudo systemctl daemon-reload
sudo systemctl Tffa657enable --now meshchatx.service
sudo systemctl status meshchatx.service
Option B: User service (no sudo system unit)
Create T383838~/.config/systemd/user/meshchatx.service:
T282828
Tff7b72[Unit]
Te6edf3DescriptionTff7b72=Ta5d6ffMeshChatX Headless (user service)
Te6edf3AfterTff7b72=Ta5d6ffnetwork-online.target
Tff7b72[Service]
Te6edf3TypeTff7b72=Ta5d6ffsimple
Te6edf3WorkingDirectoryTff7b72=Ta5d6ff%h/meshchatx
Te6edf3EnvironmentTff7b72=Ta5d6ff"Ta5d6ffPATH=%h/.local/bin:/usr/bin:/binTa5d6ff"
Te6edf3ExecStartTff7b72=Ta5d6ff%h/.local/bin/meshchatx --headless --host 0.0.0.0 --port 8000 --storage-dir %h/meshchatx/storage --reticulum-config-dir %h/.reticulum
Te6edf3RestartTff7b72=Ta5d6ffalways
Te6edf3RestartSecTff7b72=Ta5d6ff3
Tff7b72[Install]
Te6edf3WantedByTff7b72=Ta5d6ffdefault.target
Enable/start user service:
T282828
systemctl --user daemon-reload
systemctl --user Tffa657enable --now meshchatx.service
systemctl --user status meshchatx.service
If you want user services to stay active without login:
T282828
sudo loginctl enable-linger pi
Service management commands
T282828
sudo systemctl restart meshchatx.service
sudo systemctl stop meshchatx.service
sudo systemctl disable meshchatx.service
Useful logs and troubleshooting:
T282828
journalctl -u meshchatx.service -f
journalctl -u meshchatx.service -n T79c0ff200 --no-pager
systemctl show meshchatx.service -p ExecStart -p User -p Group
Reset Password
If you forget the web UI password and have SSH access to the Pi, reset it with the T383838--reset-password flag:
T282828
meshchatx --reset-password --headless --host T79c0ff0.0.0.0 --port T79c0ff8000
Or set the environment variable:
T282828
Te6edf3MESHCHAT_RESET_PASSWORDTff7b72=Tffa657true meshchatx --headless --host T79c0ff0.0.0.0 --port T79c0ff8000
This clears the stored password hash on startup. Open the web UI and you will see the Initial Setup screen where you can set a new password. After resetting, you can stop the app and restart without the flag.
Notes
• Reticulum configuration and identity data are stored in the service user's home
directory by default (for example T383838~/.reticulum and MeshChatX storage paths).
• If you attach RNode hardware by USB, make sure the service user has permission
to access serial devices (T383838dialout group on Debian-based systems).
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────